<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <link href='http://fonts.googleapis.com/css?family=Lato' rel='stylesheet' type='text/css'>
  <!-- <link rel="stylesheet/less" href="bootstrap/less/bootstrap.less">
  <script src="bootstrap/less/less-1.3.3.min.js"></script>
  -->
  <link href="bootstrap/bootstrap.css" type="text/css" rel="stylesheet"/>
  <link href="google-code-prettify/prettify.css" type="text/css" rel="stylesheet"/>
  <script type="text/javascript" src="google-code-prettify/prettify.js"></script>
  <link href="css/vertx.css" type="text/css" rel="stylesheet"/>
  <link href="css/sunburst.css" type="text/css" rel="stylesheet"/>
  <title>Vert.x</title>
  <script>
    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-30144458-1']);
    _gaq.push(['_trackPageview']);
    (function() {
      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
    })();
  </script>
</head>

<body onload="prettyPrint()" class="hp">

<div class="navbar navbar-fixed-top">
  <div class="navbar-inner">
    <div class="container">

      <a class="btn btn-navbar" data-toggle="collapse"
         data-target=".nav-collapse">
        <span class="i-bar"></span>
        <span class="i-bar"></span>
        <span class="i-bar"></span>
      </a>

      <a class="brand" href="/">Vert.x</a>

      <div class="nav-collapse">
        <ul class="nav">
          <li><a href="/">Home</a></li>
          <li><a href="downloads.html">Download</a></li>
          <li><a href="install.html">Install</a></li>
          <li><a href="docs.html">Documentation</a></li>
          <li><a href="examples.html">Examples</a></li>
          <li><a href="community.html">Project Info</a></li>
          <li><a href="https://github.com/vert-x/vert.x">Github</a></li>
          <li><a href="http://modulereg.vertx.io/">Module Registry</a></li>
          <li><a href="http://groups.google.com/group/vertx">Google Group</a></li>
          <li><a href="http://vertxproject.wordpress.com/">Blog</a></li>
        </ul>
      </div>
    </div>
  </div>
</div>

<div class="container">

  <div class="row">
    <div class="span12">
      <div class="well">
        <h1>Developing Vert.x Modules with Maven</h1>
      </div>
    </div>
  </div>

  <div class="row">
    <div class="span12">
      <div class="well">
<div>


<div class="toc">
<ul>
<li><a href="#developing-vertx-modules-with-maven">Developing Vert.x modules with Maven</a></li>
<li><a href="#generate-the-project">Generate the project</a></li>
<li><a href="#outputs">Outputs</a></li>
<li><a href="#configuring-the-project">Configuring the project</a></li>
<li><a href="#overriding-default-vertx-configuration">Overriding default Vert.x configuration</a></li>
<li><a href="#other-useful-maven-targets">Other useful Maven targets</a></li>
<li><a href="#setup-your-ide">Setup your IDE</a></li>
<li><a href="#changing-the-dependencies-of-your-project">Changing the dependencies of your project</a></li>
<li><a href="#pushing-your-module-to-maven">Pushing your module to Maven</a></li>
<li><a href="#registering-your-module-in-the-module-registry">Registering your module in the Module Registry</a></li>
<li><a href="#next-steps">Next steps</a></li>
</ul>
</div>
<h1 id="developing-vertx-modules-with-maven">Developing Vert.x modules with Maven</h1><br/>
<p>In this guide we'll show you how to develop a Vert.x project using Maven.</p>
<h1 id="generate-the-project">Generate the project</h1><br/>
<p>Vert.x provides a Maven Archetype that can generate an example Vert.x Maven project for you. You can then edit and adapt that project to develop your Vert.x module.</p>
<p>To generate a project type the following at the command line, in your project's root directory:</p>
<pre class="prettyprint">mvn archetype:generate -Dfilter=io.vertx:
</pre>
<p>This will search for any artifacts with group id <code>io.vertx</code> and interactively prompt you as to which one you want.</p>
<p>You'll also be prompted for:</p>
<ul>
<li><code>groupId</code>. This is the <code>groupId</code> for the module that we're going to generate, e.g. <code>com.mycompany</code>.</li>
<li><code>artifactId</code>. This the <code>artifactId</code> for the module that we're going to generate, e.g. <code>my-vertx-module</code>.</li>
<li><code>version</code>. This is the <code>version</code> for the module that we're going to generate, e.g. <code>2.0</code>, or <code>0.1-SNAPSHOT</code>.</li>
</ul>
<p>If you prefer you can specify these parameters on the command line, for example:</p>
<pre class="prettyprint">mvn archetype:generate -Dfilter=io.vertx: -DgroupId=com.mycompany -DartifactId=my-module -Dversion=0.1
</pre>
<p>A directory with a name corresponding to <code>artifactId</code> will be created for you, with the example project in it. Let's go into it:</p>
<pre class="prettyprint">cd my-vertx-module
</pre>
<p>It's a functioning Maven project which creates a working Vert.x module. So you can do all the normal Maven stuff, for example, try:</p>
<pre class="prettyprint">mvn install
</pre>
<p>This builds, tests and installs the module in your local Maven repository, where it can be picked up by other Vert.x modules or projects.</p>
<h1 id="outputs">Outputs</h1><br/>
<p>The outputs of the project are:</p>
<ul>
<li>The Vert.x module zip file.</li>
<li>A jar that corresponds to the module. This is useful when you have another project which depends on the classes from your module, as it allows you to add it as a dependency to your other project.</li>
</ul>
<p>The outputs are created in the <code>target</code> directory as per normal.</p>
<h1 id="configuring-the-project">Configuring the project</h1><br/>
<p>You configure several things as properties in <code>pom.xml</code> including</p>
<ul>
<li>
<p><code>module.name</code> determines the name of the module as described in the <a href="mods_manual.html#mod-id">modules manual</a></p>
</li>
<li>
<p><code>vertx.pullInDeps</code> determines whether all module dependencies should be packaged into the module as <a href="mods_manual.html#nested-mods">nested modules</a>. </p>
</li>
</ul>
<p>It also contains various properties used to configure versions of various dependencies.</p>
<h1 id="overriding-default-vertx-configuration">Overriding default Vert.x configuration</h1><br/>
<p>If you want to override any Vert.x platform configuration, e.g. <code>langs.properties</code>, <code>cluster.xml</code> or logging configuration, you can add those files to the directory <code>src/main/platform_lib</code> - these will then be added to the Vert.x platform classpath when you run the module with <code>mvn vertx:runMod</code></p>
<h1 id="other-useful-maven-targets">Other useful Maven targets</h1><br/>
<p>To run the integration tests</p>
<pre class="prettyprint">mvn integration-test
</pre>
<h1 id="setup-your-ide">Setup your IDE</h1><br/>
<p>You can use the <code>idea</code> and <code>eclipse</code> goals to create IDE projects from your Maven project, for example</p>
<pre class="prettyprint">mvn idea:idea
</pre>
<p>Or</p>
<pre class="prettyprint">mvn eclipse:eclipse
</pre>
<p>Once the IDE files have been created you can open the project in your IDE.</p>
<ul>
<li>You may have to tell your IDE to use Java source compatibility level of Java 7, as Maven seems to default to Java 5 (!)*</li>
</ul>
<h1 id="changing-the-dependencies-of-your-project">Changing the dependencies of your project</h1><br/>
<p>If your project needs a third party jar to build and you want to include it in the <code>lib</code> directory of your module you can add the dependency in the <code>dependencies</code> section of <code>pom.xml</code> with a scope of <code>compile</code>.</p>
<p>If you don't want it to be included in the <code>lib</code> directory you should add it as <code>provided</code>.</p>
<p>Once you've changed your dependencies just run <code>mvn idea:idea</code> or <code>mvn eclipse:eclipse</code> again to update your IDE project files with the new dependencies.</p>
<h1 id="pushing-your-module-to-maven">Pushing your module to Maven</h1><br/>
<p>Use <code>mvn deploy</code> as normal to push your module to a Maven repository.</p>
<h1 id="registering-your-module-in-the-module-registry">Registering your module in the Module Registry</h1><br/>
<p>If you've pushed your module to a public Maven or Bintray repository you can register it in the <a href="http://modulereg.vertx.io">Module Registry</a> so others can search for and discover it.</p>
<h1 id="next-steps">Next steps</h1><br/>
<p>Now you've got the project all set-up and running, it's time to <a href="dev_guide.html">explore the standard project layout</a> itself.</p></div>
      </div>
    </div>
  </div>

</div>

</body>
</html>